Skip to main content
POST
/
v1
/
vouchers
/
qualification
curl --request POST \
  --url https://{cluster}.voucherify.io/v1/vouchers/qualification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-App-Id: <api-key>' \
  --header 'X-App-Token: <api-key>' \
  --data '{
  "customer": {
    "source_id": "source-id",
    "metadata": {
      "key": "value"
    }
  },
  "order": {
    "amount": 10000,
    "items": [
      {
        "product_id": "product-id",
        "quantity": "1",
        "price": 10000,
        "related_object": "product",
        "product": {
          "metadata": {
            "key": "value"
          }
        }
      }
    ]
  },
  "metadata": {
    "key": "value"
  }
}'
{
  "object": "list",
  "data_ref": "data",
  "data": [
    {
      "id": "v_mkZN9v7vjYUadXnHrMza8W5c34fE5KiV",
      "code": "WVPblOYX",
      "campaign": "Gift Card Campaign",
      "campaign_id": "camp_FNYR4jhqZBM9xTptxDGgeNBV",
      "category": "<string>",
      "category_id": "cat_0bb343dee3cdb5ec0c",
      "type": "GIFT_VOUCHER",
      "discount": {
        "type": "AMOUNT",
        "amount_off": 123,
        "amount_off_formula": "<string>",
        "aggregated_amount_limit": 123,
        "effect": "APPLY_TO_ORDER",
        "is_dynamic": true
      },
      "gift": {
        "amount": 10000,
        "subtracted_amount": 123,
        "balance": 500,
        "effect": "APPLY_TO_ORDER"
      },
      "loyalty_card": {
        "points": 7000,
        "balance": 6970,
        "next_expiration_date": "2023-05-30",
        "next_expiration_points": 123,
        "pending_points": 123,
        "expired_points": 123,
        "subtracted_points": 123
      },
      "start_date": "2021-12-01T00:00:00.000Z",
      "expiration_date": "2021-12-31T00:00:00.000Z",
      "validity_timeframe": {
        "duration": "PT1H",
        "interval": "P2D"
      },
      "validity_day_of_week": [
        0
      ],
      "validity_hours": {
        "daily": [
          {
            "start_time": "12:00",
            "days_of_week": [
              0
            ],
            "expiration_time": "14:00"
          }
        ]
      },
      "active": true,
      "additional_info": "<string>",
      "metadata": {},
      "assets": {
        "qr": {
          "id": "U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK+t4pp7U7oFzjGJzj9q/bmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg+BaZk5QwXMf8k/OzSlOEVybpwSq+AiqPoNtjeuqtIgkDyvT6Q==",
          "url": "https://dev.dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX19ucFhvVmBVpVYG5KoswTsjSIaqoKg5L9ie4BK%2Bt4pp7U7oFzjGJzj9q%2FbmuMOj9mEFiVKDMIkSaruKedMvHbKoPX5Sg%2BBaZk5QwXMf8k%2FOzSlOEVybpwSq%2BAiqPoNtjeuqtIgkDyvT6Q%3D%3D"
        },
        "barcode": {
          "id": "U2FsdGVkX19eJhGfWwUrH9+tulBkON+AnMktic+N6CVWzZ9+fHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ+kJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6/pFs61apEn9SJx32ttCF6d3oxKISQQ==",
          "url": "https://dev.dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX19eJhGfWwUrH9%2BtulBkON%2BAnMktic%2BN6CVWzZ9%2BfHVxuVx22WakrzxiWXy0skuvvEHSeZIw9HlgyIJ%2BkJ1iPdUKpyENuNYJKzoZlO0mmTf6WQM6%2FpFs61apEn9SJx32ttCF6d3oxKISQQ%3D%3D"
        }
      },
      "is_referral_code": true,
      "created_at": "2021-12-22T10:13:06.487Z",
      "updated_at": "2021-12-22T10:14:45.316Z",
      "holder_id": "cust_eWgXlBBiY6THFRJwX45Iakv4",
      "referrer_id": "cust_Vzck5i8U3OhcEUFY6MKhN9Rv",
      "object": "voucher",
      "publish": {
        "object": "list",
        "count": 0,
        "url": "/v1/vouchers/WVPblOYX/publications?page=1&limit=10"
      },
      "redemption": {
        "quantity": 123,
        "redeemed_quantity": 1,
        "redeemed_points": 100000,
        "object": "list",
        "url": "/v1/vouchers/WVPblOYX/redemptions?page=1&limit=10"
      },
      "categories": [
        {
          "id": "<string>",
          "name": "<string>",
          "hierarchy": 1,
          "object": "category",
          "created_at": "2022-07-14T10:45:13.156Z",
          "updated_at": "2022-08-16T10:52:08.094Z"
        }
      ],
      "validation_rules_assignments": {
        "object": "list",
        "data_ref": "data",
        "data": [
          {
            "id": "asgm_LnY1g7UNFA9KyDrD",
            "rule_id": "val_3gPNA6SnH4ae",
            "related_object_id": "camp_CZOnEGiZfwIKWmSjhIoIT7Ol",
            "related_object_type": "campaign",
            "object": "validation_rules_assignment",
            "validation_status": "PARTIALLY_VALID",
            "validation_omitted_rules": [
              "1"
            ]
          }
        ],
        "total": 1
      },
      "applicable_to": {
        "data": [
          {
            "object": "products_collection",
            "id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
            "effect": "APPLY_TO_EVERY"
          }
        ],
        "total": 123,
        "data_ref": "data",
        "object": "list"
      },
      "inapplicable_to": {
        "data": [
          {
            "object": "products_collection",
            "id": "pc_4ndRXAsTOzwSdHcQcxf489uU",
            "effect": "APPLY_TO_EVERY"
          }
        ],
        "total": 123,
        "data_ref": "data",
        "object": "list"
      }
    }
  ],
  "total": 37,
  "id": "qfl_nAMVLoxIqSLh9O6YmfoAXRPG",
  "created_at": "2022-02-25T13:32:08.734Z",
  "tracking_id": "<string>"
}

Authorizations

​
X-App-Id
string
header
required
​
X-App-Token
string
header
required
​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
audienceRulesOnly
boolean

This parameter set to true will ask only for verifying vouchers' validation rules only against conditions applied to audiences' attributes (belonging into segment, customer metadata, customer redemption count). The remaining checks against limits and rules will be omitted during validation.

​
limit
integer

The number of vouchers to be qualified.

Required range: 1 <= x <= 50
​
order
enum<string>

Sorts the results using one of the filtering options, where the dash - means sorting in a descending order.

Available options:
created_at,
-created_at,
updated_at,
-updated_at,
code,
-code

Body

application/json

Should contain given customer and context such as an order.

Request body schema for /vouchers/qualification.

​
customer
object

This object stores customer details. You can send this object in the request body to check against vouchers requiring specific customer validation rules to be satisfied. The qualification runs against rules that are defined through the Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Audience → Customer segment or Basic Builder → Customer Activity. Read more.

​
order
object

Tracks purchase transactions. You can send the order in the request body to check against vouchers requiring specific order validation rules to be satisfied. The qualification runs against rules that are defined through the <!-- [Create Validation Rules](https://docs.voucherify.io/reference/create-validation-rules) -->Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Order structure/Order volume or Basic Builder → Order. Read more.

​
reward
object
​
metadata
object

A set of key/value pairs that you can send in the request body to check against vouchers requiring redemption metadata validation rules to be satisfied. The qualification runs against rules that are defined through the <!-- [Create Validation Rules](https://docs.voucherify.io/reference/create-validation-rules) -->Create Validation Rules endpoint or via the Dashboard; in the Advanced Rule Builder → Advanced → Redemption metadata satisfy or Basic Builder → Attributes match → REDEMPTION METADATA. Read more.

Response

200 - application/json

This operation returns the list of valid and active vouchers based on the qualification of given context (e.g., customer profile, redemptions metadata, order).

Response body schema for vouchers/qualification

​
object
string
default:list

The type of the object represented by JSON. Default is list.

​
data_ref
string
default:data

Identifies the name of the attribute that contains the array of qualified vouchers.

​
data
Voucher · object[]

Array of qualified vouchers.

​
total
integer

Total valid and active vouchers matching the qualification criteria in given context.

Example:

37

​
id
string

Unique qualification ID.

Example:

"qfl_nAMVLoxIqSLh9O6YmfoAXRPG"

​
created_at
string<date-time>

Timestamp representing the date and time when the qualification was created. The value is shown in the ISO 8601 format.

Example:

"2022-02-25T13:32:08.734Z"

​
tracking_id
string

Hashed customer source ID.

⌘I